home *** CD-ROM | disk | FTP | other *** search
/ Your Choice 3 / Your Choice Software Collection 3.iso / dos / colprint / rap.doc < prev    next >
Text File  |  1994-06-26  |  11KB  |  236 lines
  1.                              Rap version 1.3
  2.  
  3.                               June 25, 1994
  4.  
  5.                  Copyright (C) 1992-1994 by Thomas M. Roddy
  6.                             All Rights Reserved.
  7.  
  8.  
  9. Introduction:
  10.  
  11. Rap is a "word wrap" utility program which is used to reformat a text file
  12. into specified line lengths without splitting up words across lines. If a
  13. word will not fit at the end of a line, then the entire word will start
  14. the next line. This differs from programs which reformat text files to a
  15. given line length regardless of the word boundaries.
  16.  
  17. The shareware version of Rap is restricted in one way. To encourage
  18. registration, it will only process the first 120,000 characters of a file.
  19. This should be adequate to test the usefulness of the program. Please
  20. register if you find Rap useful. You will be mailed the latest version of
  21. the program without the shareware notice and with the restriction removed.
  22.  
  23. Version 1.3 differs from version 1.2 in that Rap will now accept "piping".
  24. By using the -P option, Rap will read from standard input and/or write
  25. to standard output. Also, the shareware version of Rap will now process
  26. twice as many characters as version 1.2. In addition, modifications
  27. have been made to the documentation and order form.
  28.  
  29.  
  30. License and distribution information:
  31.  
  32. Rap is shareware. It is not public domain or free software. An order form
  33. is enclosed in the file named ORDER.FRM.  After trying it out for 14 days, if
  34. you like it and want to continue using it, please register by sending the
  35. registration fee (located in ORDER.FRM) with your name and address along with
  36. any comments or questions to the address listed.
  37.  
  38. You may NOT alter the code nor may you sell this program or any of its
  39. associated data files for any price.  You may charge a reasonable copy
  40. fee of not more than US$10 when distributing it to others as long as you
  41. clearly stipulate that Rap must be registered with its author if it is
  42. used beyond the trial period. Every copy of the ZIP distribution file
  43. must contain all of the files listed below.
  44.  
  45. You may (and are encouraged to) distribute the shareware version of Rap
  46. to others. Under no circumstances may you distribute a registered version
  47. of Rap to others.
  48.  
  49.  
  50. Disclaimer:
  51.  
  52. The author makes no claims or guarantees about the use of Rap and will
  53. not be responsible for any loss, including data or profits, due its use
  54. or misuse.
  55.  
  56.  
  57. Compatibility:
  58.  
  59. Rap should work with all standard ASCII files. It has not been tested with
  60. files containing control characters commonly found in documents in specific
  61. word processing formats such as Word Perfect or Microsoft Word. Most
  62. word processors allow you to convert documents to ASCII format. You should
  63. do this before using Rap on the documents. Alternatively, you can use
  64. the utilities in the File Format Utilities to get your text into an
  65. acceptable format. See the bottom of this document for more information.
  66.  
  67. Rap should work with UNIX generated files which may have line feeds
  68. without the accompanying carriage returns generally found in MS-DOS
  69. generated files. It should also work with Macintosh generated files.
  70. The output file generated by Rap will, however, have a carriage return
  71. and line feed at the end of each line.
  72.  
  73.  
  74. Files in distribution:
  75.  
  76.  RAP.EXE     -  Rap executable program
  77.  RAP.DOC     -  This file - Documentation for Rap
  78.  ORDER.FRM   -  Printable order form for registering programs
  79.  FILE_ID.DIZ -  Short description of Rap
  80.  
  81.  
  82. Product description:
  83.  
  84. Rap will "word wrap" lines of text to fit into the line width specified
  85. on the command line. If a full word cannot fit on the end of one line,
  86. the entire word is wrapped to the next line. Rap will not hypenate words
  87. that are not already hypenated, but will unhyphenate words that are hyphen-
  88. ated at the end of a line (as in the above line) since the hyphenation is
  89. meaningless (actually confusing and incorrect) if it appears in the middle
  90. of a line after being reformatted by Rap.
  91.  
  92. If a line width is not specified, then Rap will default to the largest line
  93. width it supports which is 2147483647 characters per line. This effectively
  94. removes all line breaks within a paragraph. Acceptable values are from 10 to
  95. 2147483647 and can be specified using the /W option. Most other word wrap
  96. programs can not handle line lengths this long. This useful when dealing
  97. with long paragraphs which contain no line breaks. The paragraph appears
  98. as one very large line.
  99.  
  100. Rap also allows you to specify the size of the two internal buffers which
  101. are used in processing the file. The default sizes for the two buffers are
  102. 2048 bytes each. You can modify this value by using the /B option. Acceptable
  103. values are from 128 to 30208 bytes. If performance is critical, you could
  104. optimize the processing time by setting these buffer sizes, but in my testing
  105. 2048 bytes seems to be the most efficient value.
  106.  
  107. Using the /M option will activate "margin mode" to also wrap paragraphs that
  108. have an indented starting position.
  109.  
  110. Specifying the output file name is optional.  If no output file name is given,
  111. the output file name will default to the input file name with the extension
  112. .RAP appended to it.  For example, the input file TEXTFILE would default to
  113. the output file TEXTFILE.RAP while TEXTFILE.TXT would also default to
  114. TEXTFILE.RAP.  Rap will error if the input file has the same name as the
  115. output file.
  116.  
  117. Many word processing programs reformat paragraphs themselves depending
  118. on how many characters can fit on a line. This is frequently dependent
  119. upon font size, margins, etc. By removing the "line breaks", these programs
  120. can process the file better because they don't have to worry about "line
  121. breaks" which are already in the file. Rap is therefore very useful when
  122. converting documents between different word processors. In some cases, you
  123. may want to put in line breaks after 80 characters, while other times you
  124. may want to strip out all the line breaks within a paragraph and let the
  125. word processor do the reformatting.
  126.  
  127. Most word processor programs save their files in a proprietary format with
  128. control characters. If the text file is not in ASCII format, you must convert
  129. it to ASCII. Most word processors allow you to do this.
  130.  
  131. Reformatting documents using word wrap programs often have undesirable side
  132. effects so this type of text processing is dependent upon the text files you
  133. want to print.
  134.  
  135. Usage:  Rap infile [-Wm] [-Bn] [-M] [-P] [outfile]
  136.  
  137.    where m is the desired line width:
  138.          minimum=10, maximum=2147483647, default=2147483647
  139.    where n is the desired buffer size
  140.          minimum=128, maximum=30208, default=2048
  141.    where M implements margin mode.
  142.  
  143.    -P indicates that piping of input and/or output is being performed
  144.  
  145. Examples:
  146.  
  147.     RAP TEXTFILE.TXT /W76
  148.           Reformats TEXTFILE.TXT into 76 characters per line and writes
  149.           it to TEXTFILE.RAP
  150.  
  151.     RAP TEXTFILE.TXT
  152.           Reformats TEXTFILE.TXT into 2147483647 characters per line and
  153.           writes it to TEXTFILE.RAP. This effectively removes all line breaks
  154.           within paragraphs. Useful for importing the document to word
  155.           processors which do not like line breaks.
  156.  
  157.     RAP TEXTFILE.TXT /W50
  158.           Reformats TEXTFILE.TXT into 50 characters per line and writes
  159.           it to TEXTFILE.RAP. This is useful for printing the output file
  160.           in three columns (using ColPrint) on a printer that supports 160
  161.           characters per line (20 cpi) mode.
  162.  
  163.     RAP TEXTFILE.TXT /W50 /B8096 TEXT2.TXT
  164.           Reformats TEXTFILE.TXT into 50 characters per line and writes
  165.           it to TEXT2.TXT. The two internal buffers are each 8 KB in
  166.           size.
  167.  
  168.     RAP TEXTFILE.TXT /W50 /B8096 /M TEXT2.TXT
  169.           Reformats TEXTFILE.TXT into 50 characters per line and writes
  170.           it to TEXT2.TXT. The two internal buffers are each 8 KB in
  171.           size. If an entire paragraph is indented, then it will also be
  172.           "word wrapped" while maintaining the indentation.
  173.  
  174. RAP.EXE should be placed in a directory which is in your search PATH so that
  175. you can run the program from within other directories.
  176.  
  177.  
  178. Miscellaneous information:
  179.  
  180. When using the -P option, you should not specify file names for output
  181. and possibly not even for input. If you are piping data as standard input
  182. into Rap, but want to save the results to a file, you should use DOS
  183. redirection to do this since if only one file name is listed in the
  184. command line, it will be assumed to be the output file's name.
  185.  
  186. Example: TYPE INPUT.DOC | Rap -W72 -P > OUTPUT.DOC
  187.  
  188. Warning: you are not legally allowed to modify many copyrighted software
  189. manuals. This program should be used on your own personal files or with the
  190. permission of the document's author.
  191.  
  192. I have written several utilities to aid you in preprocessing text files
  193. so that Rap can work better on more formats of documents. These utility
  194. programs are grouped together and called the File Format Utilities and
  195. can be found as FFU10.ZIP on many BBS's. This package is also Shareware.
  196.  
  197. The purpose of the File Format Utilities is to aid in preparing documents
  198. so that they are in a format that other text processing programs can
  199. systematically work with. Programs that perform functions such as "word wrap"
  200. will be able to reformat documents with minimal problems if the document
  201. follows a few rules. The following utilities help you modify document files
  202. to adhere to these rules. The utilities that make up the package are
  203. listed below with very brief descriptions:
  204.  
  205.   FixEOLs - Converts all lines to end in an ASCII standard CR/LF character pair
  206.   Untab   - Expands TAB characters to any number of spaces
  207.   Strip   - Removes given characters from a file
  208.   Parafy  - Insert blank line if a line begins past acceptable margin
  209.   FixShort -Insert blank line after short lines
  210.   FndStart -Insert blank line after lines which begin with a given string
  211.   FndRep  - Finds a given string and removes or replaces it with another
  212.  
  213. If you are looking for a printing program to print your files into newspaper
  214. style columns, take a look at another shareware program by this author called
  215. ColPrint. ColPrint is compatible with many dot matrix, DeskJet, and laser
  216. printers. The file is COLPR21.ZIP and is on many BBS's. If you can't find it
  217. on your local BBS, download it from CompuServe. If you do not have access to
  218. CompuServe, send $5 to the address below and I'll mail you a Shareware copy
  219. to evaluate or send $9.95 + $1 (shipping/handling) for a registered
  220. unrestricted version.
  221.  
  222. The official distribution site for the programs is the Programmers Corner BBS
  223. in Columbia, Maryland (410) 995-6874. You can be sure of having the latest
  224. version of Rap if you download it from there. CompuServe will have it soon
  225. after the Programmers Corner. I can also be reached on the Programmers Corner
  226. BBS for technical support by sending a message to Tom Roddy.
  227.  
  228. The author can also be contacted by US mail, CompuServe, or the Internet:
  229.  
  230.  Thomas M. Roddy              CompuServe ID:  73730,3304
  231.  7158 Harp String             Internet: 73730.3304@compuserve.com
  232.  Columbia, MD  21045
  233.  
  234.  
  235. Trademarks are the property of their respective owners.
  236.